'---------------------------------------------------------------------------------------------------
'STRING ARRAY
'---------------------------------------------------------------------------------------------------
'SUMMARY
'   Purpose:  A library of custom subroutines and functions to create and manipulate a dnynamic array of strings.
'   Author:   Dustinian Camburides
'   Platform: QB64 (www.qb64.net)
'   Revision: 1.0
'   Updated:  7/7/2012
'---------------------------------------------------------------------------------------------------
'REVISION HISTORY
'   1.0: First working version.
'---------------------------------------------------------------------------------------------------
'PLANNED ENHNACEMENTS
'   Minor:
'       - Add comments to procedures.
'   Major:
'       - None at this time.
'---------------------------------------------------------------------------------------------------
'PROCEDURES
'   - SUB Seperate_Lines (Sub_Strings() AS STRING, Text AS STRING, Seperator AS STRING)
'   - SUB Remove_Blank_Words (Words() AS STRING)
'   - SUB Remove_Word(Words() AS STRING, Index AS INTEGER)
'---------------------------------------------------------------------------------------------------
SUB Seperate_Lines (Array_of_Strings() AS STRING, Text AS STRING, Seperator AS STRING)
    'SUMMARY:
        '[Seperate_Lines] extracts individual sub-strings from a string.
    'INPUT:
        'Array_of_Strings(): The output array, where seperate [sub-strings] are stored.
        'Text: The input string being filtered.
        'Seperator: The character(s) that seperates [sub-strings].
    'VARIABLES:
        DIM lngLocation AS LONG 'The location of the [Seperator] within the [Text].
        DIM lngStart AS LONG    'The starting point for the next search for a [Seperator] within the [Text].
        DIM intLines AS INTEGER 'The total number of lines in the dynamic array.
    'INITIALIZE:
        Text = Text + Seperator
        intLines = 0
        lngStart = 1
        lngLocation = INSTR(lngStart, Text, Seperator)
    'PROCESSING:
        'While the [Seperator] appears in the [Text]...
            WHILE (lngLocation > 0)
                'Increment the number of lines:
                    intLines = intLines + 1
                'Re-size the dynmaic array:
                    REDIM _PRESERVE Array_of_Strings(intLines) AS STRING
                'Extract the [sub-string] from the [Text]:
                    Array_of_Strings(intLines) = MID$(Text, lngStart, (lngLocation - lngStart))
                'Move the [Start] pointer beyond the end of the [sub-string]:
                    lngStart = lngLocation + 1
                'Locate the next [Seperator] within the [Text]:
                    lngLocation = INSTR(lngStart, Text, Seperator)
        'Next instance of [Seperator]...
            WEND
END SUB

SUB Remove_Blank_Words (Array_of_Strings() AS STRING)
    'SUMMARY:
        '[Remove_Blank_Words] removes blank elements from a dynamic array of strings.
    'INPUT/OUTPUT:
        'Array_of_Strings(): The dynamic array, where seperate elements are stored.
    'VARIABLES:
        DIM intElement AS INTEGER 'The element within the array.
    'PROCESSING:
        'For each [Element] in the [Array]...
            FOR intElement = UBOUND(Array_of_Strings) TO LBOUND(Array_of_Strings) STEP -1
                'If the word is blank...
                    IF Array_of_Strings(intElement) = "" THEN
                        'Remove the word:
                            Call Remove_Word(Array_of_Strings(), intElement)
                    END IF
            NEXT intElement
END SUB

SUB Remove_Word(Array_of_Strings() AS STRING, Index AS INTEGER)
    'SUMMARY:
        '[Remove_Word] removes a word from a dynamic array of strings.
    'INPUT:
        'Array_of_Strings(): The dynamic array, where seperate elements are stored.
        'Index: The element to be removed from the dynamic array.
    'VARIABLES:
        DIM intWord AS INTEGER
    'PROCESSING:
        'For each [word] after [Index]...
            FOR intWord = Index to UBOUND(Array_of_Strings)-1
              'Replace the word with the subsequent word:
                Array_of_Strings(intWord) = Array_of_Strings(intWord + 1)
        'Next [word]...
            NEXT intWord
        'Redimension the [Words] array:
          REDIM _PRESERVE Array_of_Strings(UBOUND(Array_of_Strings)-1) AS STRING
END SUB
